<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
  
  <!-- Licensed under the Apache 2.0 License -->
  <link rel="stylesheet" type="text/css" href="_static/fonts/open-sans/stylesheet.css" />
  <!-- Licensed under the SIL Open Font License -->
  <link rel="stylesheet" type="text/css" href="_static/fonts/source-serif-pro/source-serif-pro.css" />
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap.min.css" />
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap-theme.min.css" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
    <title>For Developers &#8212; ElasticHQ latest documentation</title>
    
    <link rel="stylesheet" href="_static/guzzle.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     'latest',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="ElasticHQ latest documentation" href="index.html" />
    <link rel="next" title="FAQ" href="faq.html" />
    <link rel="prev" title="REST API" href="rest-api.html" />
  
   

  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="http-routingtable.html" title="HTTP Routing Table"
             >routing table</a> |</li>
        <li class="right" >
          <a href="faq.html" title="FAQ"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="rest-api.html" title="REST API"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">ElasticHQ latest documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="container-wrapper">

      <div id="mobile-toggle">
        <a href="#"><span class="glyphicon glyphicon-align-justify" aria-hidden="true"></span></a>
      </div>
  <div id="left-column">
    <div class="sphinxsidebar"><a href="
    index.html" class="text-logo">ElasticHQ</a>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <h2>Table Of Contents</h2>
  </div>
  <div class="sidebar-toc">
    
    
      <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="installation.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="rest-api.html">REST API</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">For Developers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#contributing">Contributing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#developer-environment">Developer Environment</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#set-debug-to-true">Set Debug to True</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#building-pre-releases">Building Pre-Releases</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#install-build-the-ui">Install/Build the UI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#building-a-distribution">Building a Distribution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pulling-a-tag-from-dockerhub">Pulling a tag from DockerHub</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#running-tests">Running Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#manual-testing">Manual Testing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#notes">Notes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#building-documentation">Building Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#http-responses">HTTP Responses</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#http-status">HTTP Status</a></li>
<li class="toctree-l3"><a class="reference internal" href="#response-headers">Response Headers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#issues-bugs">Issues/Bugs</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>

    
  </div>
</div>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <div id="main-search">
      <form class="form-inline" action="search.html" method="GET" role="form">
        <div class="input-group">
          <input name="q" type="text" class="form-control" placeholder="Search...">
        </div>
        <input type="hidden" name="check_keywords" value="yes" />
        <input type="hidden" name="area" value="default" />
      </form>
    </div>
  </div>
</div>
      
    </div>
  </div>
        <div id="right-column">
          
          <div role="navigation" aria-label="breadcrumbs navigation">
            <ol class="breadcrumb">
              <li><a href="index.html">Docs</a></li>
              
              <li>For Developers</li>
            </ol>
          </div>
          
          <div class="document clearer body">
            
  <div class="section" id="for-developers">
<h1>For Developers<a class="headerlink" href="#for-developers" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#contributing" id="id1">Contributing</a></li>
<li><a class="reference internal" href="#developer-environment" id="id2">Developer Environment</a><ul>
<li><a class="reference internal" href="#set-debug-to-true" id="id3">Set Debug to True</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-pre-releases" id="id4">Building Pre-Releases</a><ul>
<li><a class="reference internal" href="#install-build-the-ui" id="id5">Install/Build the UI</a></li>
<li><a class="reference internal" href="#building-a-distribution" id="id6">Building a Distribution</a></li>
<li><a class="reference internal" href="#pulling-a-tag-from-dockerhub" id="id7">Pulling a tag from DockerHub</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-tests" id="id8">Running Tests</a></li>
<li><a class="reference internal" href="#manual-testing" id="id9">Manual Testing</a><ul>
<li><a class="reference internal" href="#notes" id="id10">Notes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-documentation" id="id11">Building Documentation</a></li>
<li><a class="reference internal" href="#http-responses" id="id12">HTTP Responses</a><ul>
<li><a class="reference internal" href="#http-status" id="id13">HTTP Status</a></li>
<li><a class="reference internal" href="#response-headers" id="id14">Response Headers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#issues-bugs" id="id15">Issues/Bugs</a></li>
</ul>
</div>
<div class="section" id="contributing">
<h2><a class="toc-backref" href="#id1">Contributing</a><a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h2>
<p>Please read the <a class="reference external" href="https://github.com/ElasticHQ/elasticsearch-HQ/blob/master/CONTRIBUTING.md">Contributing guidelines</a> before working on a pull request.</p>
<p>Note that new features and bug fixes should be performed from <cite>develop</cite> and on a new feature branch for the pull request to be manageable.</p>
</div>
<div class="section" id="developer-environment">
<h2><a class="toc-backref" href="#id2">Developer Environment</a><a class="headerlink" href="#developer-environment" title="Permalink to this headline">¶</a></h2>
<div class="section" id="set-debug-to-true">
<h3><a class="toc-backref" href="#id3">Set Debug to True</a><a class="headerlink" href="#set-debug-to-true" title="Permalink to this headline">¶</a></h3>
<p>It is preferred that while developing, <code class="docutils literal"><span class="pre">debug</span></code> be set to True, by starting the application with <code class="docutils literal"><span class="pre">python</span> <span class="pre">application.py</span> <span class="pre">-d</span> <span class="pre">True</span></code>.</p>
<p>This will guarantee that any code changes will immediately refresh the application and cause it to start again with the new changes.</p>
</div>
</div>
<div class="section" id="building-pre-releases">
<h2><a class="toc-backref" href="#id4">Building Pre-Releases</a><a class="headerlink" href="#building-pre-releases" title="Permalink to this headline">¶</a></h2>
<p>Pre-Releases are typically not built in a distributable format until the very end of the development cycle. For this reason,
pre-release versions have to be built manually - with the UI and API working in separate directories.</p>
<div class="section" id="install-build-the-ui">
<h3><a class="toc-backref" href="#id5">Install/Build the UI</a><a class="headerlink" href="#install-build-the-ui" title="Permalink to this headline">¶</a></h3>
<p>Navigate to the root directory of the project...</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">npm</span> <span class="pre">install</span></code></li>
<li><code class="docutils literal"><span class="pre">npm</span> <span class="pre">start</span></code></li>
<li>Server should be running on <code class="docutils literal"><span class="pre">http://localhost:8080</span></code></li>
</ol>
<p>You still need to start the python server, but that is accomplished as normal:</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements.txt</span></code></li>
<li><code class="docutils literal"><span class="pre">python</span> <span class="pre">application.py</span></code></li>
</ol>
<p>In this case, using a development version, the API will be running on port <code class="docutils literal"><span class="pre">5000</span></code>, and the UI will be accessible on port <code class="docutils literal"><span class="pre">8080</span></code>.</p>
</div>
<div class="section" id="building-a-distribution">
<h3><a class="toc-backref" href="#id6">Building a Distribution</a><a class="headerlink" href="#building-a-distribution" title="Permalink to this headline">¶</a></h3>
<p>To build the final distribution that will have the UI and API accessible from port <code class="docutils literal"><span class="pre">5000</span></code>, run <code class="docutils literal"><span class="pre">npm</span> <span class="pre">run-script</span> <span class="pre">build</span></code>.</p>
<p>This will create an <code class="docutils literal"><span class="pre">index.html</span></code> that the Flask server will serve, under <code class="docutils literal"><span class="pre">/elastichq/templates</span></code> and static file bundles under <code class="docutils literal"><span class="pre">/elastichq/static</span></code>.</p>
<p>Once the distribution is built, you can start the server with <code class="docutils literal"><span class="pre">python</span> <span class="pre">application.py</span></code> and view the application at <code class="docutils literal"><span class="pre">http://localhost:5000</span></code></p>
</div>
<div class="section" id="pulling-a-tag-from-dockerhub">
<h3><a class="toc-backref" href="#id7">Pulling a tag from DockerHub</a><a class="headerlink" href="#pulling-a-tag-from-dockerhub" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal"><span class="pre">develop</span></code> branch is automatically built on dockerhub. If you wish to test using this tag, which is latest unstable:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>docker run -p <span class="m">5000</span>:5000 elastichq/elasticsearch-hq:develop
</pre></div>
</div>
</div>
</div>
<div class="section" id="running-tests">
<h2><a class="toc-backref" href="#id8">Running Tests</a><a class="headerlink" href="#running-tests" title="Permalink to this headline">¶</a></h2>
<p>All tests run using docker containers for specific versions of ES. Running the entire suite will run against all containers, one at a time.</p>
<p>To run all tests across all ES major versions:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>./run-tests.sh
</pre></div>
</div>
<p>To run tests for a specific major version of ES:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>python manage.py run-tests --esv<span class="o">=</span>&lt;MAJOR_VERSION&gt;
</pre></div>
</div>
</div>
<div class="section" id="manual-testing">
<h2><a class="toc-backref" href="#id9">Manual Testing</a><a class="headerlink" href="#manual-testing" title="Permalink to this headline">¶</a></h2>
<p>The code repo contains docker compose files for testing against different Elasticsearch versions.</p>
<p>You can run these individually and then use the applicaiton to test against it:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="nb">cd</span> /tests/local/v2
docker-compose up
</pre></div>
</div>
<p>Or you can run them all at once and test against them:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="nb">cd</span> /tests/local
./run_es_versions.sh
</pre></div>
</div>
<p>To bring the containers down:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>./kill_es_versions.sh
</pre></div>
</div>
<p>In the event of errors to the effect of &#8220;container name in use&#8221;, list the containers and remove them. This will remove all stopped containers:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>docker container ls
docker container prune
</pre></div>
</div>
<div class="section" id="notes">
<h3><a class="toc-backref" href="#id10">Notes</a><a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Coverage report will be appear under <code class="docutils literal"><span class="pre">/tests/htmlcov</span></code>.</li>
<li>HTML report of pytest output will appear under <code class="docutils literal"><span class="pre">/tests/htmlout</span></code></li>
</ul>
</div>
</div>
<div class="section" id="building-documentation">
<h2><a class="toc-backref" href="#id11">Building Documentation</a><a class="headerlink" href="#building-documentation" title="Permalink to this headline">¶</a></h2>
<p>Sphinx requires specific libraries that are not in the default <code class="docutils literal"><span class="pre">requirements.txt</span></code>.</p>
<p>First install the sphinx requirements: <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">sphinx-requirements.txt</span></code></p>
<p>To generate the documentation:</p>
<p><code class="docutils literal"><span class="pre">./sphinx-build</span> <span class="pre">-b</span> <span class="pre">html</span> <span class="pre">/path/to/docs/source</span> <span class="pre">/path/to/docs</span></code></p>
</div>
<div class="section" id="http-responses">
<h2><a class="toc-backref" href="#id12">HTTP Responses</a><a class="headerlink" href="#http-responses" title="Permalink to this headline">¶</a></h2>
<div class="section" id="http-status">
<h3><a class="toc-backref" href="#id13">HTTP Status</a><a class="headerlink" href="#http-status" title="Permalink to this headline">¶</a></h3>
<p>All response codes are included in the HTTP Status response header. There are method-specific responses to take note of:</p>
<ul class="simple">
<li>POST - Returns <code class="docutils literal"><span class="pre">201</span></code></li>
<li>PUT - Returns <code class="docutils literal"><span class="pre">200</span></code></li>
<li>DELETE - Returns <code class="docutils literal"><span class="pre">200</span></code></li>
</ul>
</div>
<div class="section" id="response-headers">
<h3><a class="toc-backref" href="#id14">Response Headers</a><a class="headerlink" href="#response-headers" title="Permalink to this headline">¶</a></h3>
<p>Standard header response below:</p>
<div class="highlight-http"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
<span class="na">Access-Control-Allow-Credentials</span><span class="o">:</span> <span class="l">true</span>
<span class="na">Access-Control-Allow-Methods</span><span class="o">:</span> <span class="l">POST, OPTIONS, GET, PUT, DELETE</span>
<span class="na">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="l">*</span>
<span class="na">Access-Control-Max-Age</span><span class="o">:</span> <span class="l">3600</span>
<span class="na">Allow</span><span class="o">:</span> <span class="l">POST, GET, PUT, DELETE</span>
<span class="na">Content-Length</span><span class="o">:</span> <span class="l">4320</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="na">Date</span><span class="o">:</span> <span class="l">Wed, 31 Jan 2018 22:54:08 GMT</span>
<span class="na">Server</span><span class="o">:</span> <span class="l">Werkzeug/0.14.1 Python/3.5.0</span>
<span class="na">Status</span><span class="o">:</span> <span class="l">200</span>
<span class="na">X-HQ-Response-Time</span><span class="o">:</span> <span class="l">2570</span>
</pre></div>
</div>
<p>Custom headers are pre-fixed with <code class="docutils literal"><span class="pre">X-HQ</span></code>.</p>
<ul class="simple">
<li>X-HQ-Response-Time: The time, in milliseconds it took from request to response.</li>
</ul>
</div>
</div>
<div class="section" id="issues-bugs">
<h2><a class="toc-backref" href="#id15">Issues/Bugs</a><a class="headerlink" href="#issues-bugs" title="Permalink to this headline">¶</a></h2>
<p>Patches, bug reports, and feature requests are all welcome through the <a class="reference external" href="https://github.com/ElasticHQ/elasticsearch-HQ/">GitHub site</a>. Contributions in the form of patches or pull requests are easier to integrate and will receive priority attention.</p>
</div>
</div>


          </div>
            
  <div class="footer-relations">
    
      <div class="pull-left">
        <a class="btn btn-default" href="rest-api.html" title="previous chapter (use the left arrow)">REST API</a>
      </div>
    
      <div class="pull-right">
        <a class="btn btn-default" href="faq.html" title="next chapter (use the right arrow)">FAQ</a>
      </div>
    </div>
    <div class="clearer"></div>
  
        </div>
        <div class="clearfix"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="http-routingtable.html" title="HTTP Routing Table"
             >routing table</a> |</li>
        <li class="right" >
          <a href="faq.html" title="FAQ"
             >next</a> |</li>
        <li class="right" >
          <a href="rest-api.html" title="REST API"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">ElasticHQ latest documentation</a> &#187;</li> 
      </ul>
    </div>
<script type="text/javascript">
  $("#mobile-toggle a").click(function () {
    $("#left-column").toggle();
  });
</script>
<script type="text/javascript" src="_static/js/bootstrap.js"></script>
  <div class="footer">
    &copy; Copyright 2018, ElasticHQ. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  </div>
    <script type="text/javascript">
      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-40876494-1']);
      _gaq.push(['_trackPageview']);
      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();
    </script>
  </body>
</html>